///////////////////////////////////////////////////////////////////////////////
//
//  Copyright (C) 2007-2009 ILOG, S.A.
//  All Rights Reserved.
//  The following is ILOG Source Code.  No modifications may be made to the  
//  ILOG Source Code.  Any usage of the ILOG Source Code is subject to 
//  the terms and conditions of the ILOG End User License Agreement   
//  applicable to this ILOG software product.
//
///////////////////////////////////////////////////////////////////////////////

package ilog.gauges.gaugesClasses
{
  import flash.events.Event;
  
  import ilog.gauges.TickItem;

  [DefaultProperty("categories")]
  
  /**
   *  The <code>CategoryScale</code> class lets a scale represent data
   *  grouped by a set of discrete string values.
   *  <p>
   *  You typically do not use the <code>CategoryScale</code> class directly.
   *  Instead, you use one of its subclasses, such as <code>CircularCategoryScale</code> 
   *  or <code>RectangularCategoryScale</code>.
   *  </p>
   *  Categories are defined by the <i>categories</i> array. 
   *   
   *  @mxml
   *  
   *  <p>The <code>&lt;CategoryScale&gt;</code> tag inherits all the properties
   *  of its parent classes and adds the following properties:</p>
   *  
   *  <pre>
   *  &lt;CategoryScale
   *    <strong>Properties</strong>
   *    categories="[]"
   *  /&gt;
   *  </pre>
   * 
   *  @see ilog.gauges.circular.CircularCategoryScale
   *  @see ilog.gauges.rectangular.RectangularCategoryScale
   *  
   */
  public class CategoryScale extends ScaleBase
  {
    /**
     * Constructor 
     */     
    public function CategoryScale()
    {
      super();
    }
    
    /**
     *  @private
     *  Storage for the categories property.
     */
    private var _categories:Array = [];
    [Bindable("categoriesChanged")]
    [Inspectable(category="Gauge", arrayType="String")]

    /**
     * An array of <code>String</code> values which correspond to the categories represented by the scale.
     * Each category must be unique.
     * 
     */
    public function get categories():Array
    {
      return _categories;
    }

    /**
     *  @private
     */
    public function set categories(value:Array):void
    {
      _categories = value;
      invalidateTicks();
      dispatchEvent(new Event("categoriesChanged"));
    }

    /**
     *  @private
     */
    override protected function buildMajorTickItems():Array
    {
      var majorTickCache:Array = [];

      var majorTickCount:Number = categories.length;
      var data:TickItem;
      var cpos:Number;

      for (var i:int = 0; i < majorTickCount; i++) {
        data = new TickItem(this);
        data.isMinor = false;
        data.value = categories[i];
        cpos = i / (majorTickCount - 1);
        data.position = cpos;
        majorTickCache.push(data); 
      }

      return majorTickCache;      
    }

    /**
     * The index of a category in the <i>categories</i> array.
     * @param key The category to get the index for.
     * @return The index of the category. 
     */    
    public function getCategoryIndex(key:String):int
    {
      for (var i:int = 0; i < _categories.length; i++) {
        if (categories[i] == key)
          return i;
      } 
      return -1;
    }    
  }
}
